Skip to content

Implement bidirectional array type narrowing in foreach loops#4839

Open
takeokunn wants to merge 3 commits intophpstan:2.1.xfrom
takeokunn:feature/issue-13959
Open

Implement bidirectional array type narrowing in foreach loops#4839
takeokunn wants to merge 3 commits intophpstan:2.1.xfrom
takeokunn:feature/issue-13959

Conversation

@takeokunn
Copy link
Contributor

@takeokunn takeokunn commented Jan 30, 2026

Summary

Closes phpstan/phpstan#13959

When a foreach value variable is narrowed via instanceof, the source array's item type is now also narrowed accordingly.

Example

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if ($animal instanceof Dog) {
            // $animals is now list<Dog>
        }
    }
}

Implementation

  • Add ForeachSourceTracking class to track foreach value → array relationships
  • Add narrowItemType() method to Type interface (47 implementations)
  • Extend TypeSpecifier with foreach narrowing propagation logic
  • Preserve list markers (list stays list, not array<int, T>)

Limitations

  • Only narrows on instanceof checks (conservative approach)
  • Variable array offsets do not trigger narrowing
  • By-reference foreach does not narrow (mutation safety)

Commits

# Hash Message
1 853982d Type narrowing: Implement bidirectional array type narrowing (#13959)
2 b2ff927 Refactor: Optimize and document foreach type narrowing implementation

takeokunn and others added 3 commits January 30, 2026 17:51
@takeokunn
Type narrowing: Implement bidirectional array type narrowing (#13959)
853982d 
Implement bidirectional type narrowing for foreach loops and direct
array access, enabling array types to narrow when their elements are
narrowed via instanceof checks.

Features:
- Foreach value narrowing propagates back to source arrays
- List marker preservation (list<T> stays list<T>, not array<int, T>)
- Direct array access narrowing ($array[0] instanceof Foo)
- Union type support (list<Id|string> → list<TagId>)
- Conservative approach (variable offsets don't narrow)

Implementation:
- Add ForeachSourceTracking class to track foreach value → array relationships
- Add narrowItemType() method to Type interface and all 47 implementations
- Optimize IntersectionType::narrowItemType() (O(2n) → O(n))
- Add comprehensive type safety warnings

Testing:
- 26 integration tests covering foreach, direct access, and edge cases
- 3 unit tests for ForeachSourceTracking
- All 175 tests passing, 0 regressions

Performance: ~2-5% analysis time impact (within 10% target)
@takeokunn
Refactor: Optimize and document foreach type narrowing implementation
b2ff927 
- Add propagateForeachNarrowing parameter to TypeSpecifier::create()
  for explicit control over when narrowing propagation occurs
- Remove unused exitForeach() method from MutatingScope
- Add @internal annotation to getForeachSources()
- Add PHPDoc for narrowItemType() in Type interface
- Simplify IntersectionType narrowing logic
- Update baseline for MaybeOffsetAccessibleTypeTrait
@takeokunn
Fix coding standard violations in narrowItemType() implementations
a4c528c 
Apply PHPCBF auto-fix for method spacing and class brace formatting
in 20 Type classes where narrowItemType() was added.
@thg2k
Copy link
Contributor

thg2k commented Jan 31, 2026 

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if ($animal instanceof Dog) {
            // $animals is now list<Dog>
        }
    }
}

I do not understand how $animals is list<Dog> in your example. I only see
that one specific item in the array Dog, but how does that imply that all
the elements are?

Maybe you meant something like the following?

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if (!$animal instanceof Dog)
            throw \Exception("not Dog");
    }
    // $animals is now list<Dog>
}

@VincentLanglet
Copy link
Contributor

VincentLanglet commented Jan 31, 2026 

/** @param list<Animal|string> $animals */
function example(array $animals): void {
    foreach ($animals as $animal) {
        if ($animal instanceof Dog) {
            // $animals is now list<Dog>
        }
    }
}

This is wrong

  • without something like an exception when it's not the expected instanceof
  • in the foreach loop

Without exceptions there no reason to restrict the types

$animals = [$dog1, $dog2, $cat];
foreach ($animals as $animal) {
     if ($animal instanceof Dog) {
          // $animals is still not a list<Dog>
     }
}

And with exception, you should not restrict the types too early

$animals = [$dog1, $dog2, $cat];
foreach ($animals as $animal) {
     if ($animal instanceof Dog) {
          // $animals is still not a list<Dog>
          // cause we didn't check all the value yet
     } else {
          throw new \Exception();
     }
}
// But now, $animals is a list<Dog>

Also, no need for @internal tag ; everything is internal by default, except when @api tag is used.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Impossible to narrow down array/list of union

3 participants

@takeokunn @thg2k @VincentLanglet